feat: v2 dual-write for checkpoints behind feature flag by pfleidi · Pull Request #759 · entireio/cli

pfleidi · 2026-03-23T23:57:02Z

Summary

Introduces checkpoints v2 dual-write support. When checkpoints_v2 is enabled in strategy options, the CLI writes checkpoint data to both v1 (entire/checkpoints/v1 branch) and v2 custom refs (refs/entire/checkpoints/v2/main and refs/entire/checkpoints/v2/full/current).

V2GitStore — new store type for v2 ref operations, separate from GitStore (v1) to simplify future v1 removal
/main ref — receives metadata, prompts, session metadata (no raw transcript). Compact transcript.jsonl will be added here once compaction (workstream B) is ready
/full/current ref — receives raw transcript (full.jsonl) + content_hash.txt. Each write replaces the entire tree (no accumulation); generation rotation is future work
Dual-write wiring — CondenseSession and stop-time finalization both dual-write, gated by settings.IsCheckpointsV2Enabled(). V2 failures are best-effort (logged as warnings, never block v1)
Shared validation — extracted validateWriteOpts used by both v1 and v2 stores

What's NOT in scope (future steps per design spec)

Task checkpoint support on /main
Push logic for v2 refs
Read paths (entire status, entire explain, entire resume)
Generation rotation for /full/current
Compact transcript format / compaction (workstream B)
v1 → v2 migration tool

Test plan

20 unit tests for V2GitStore (ref management, write/update for both refs, multi-session, edge cases)
2 strategy-level tests (v2 enabled vs disabled in CondenseSession)
3 integration tests (full workflow, disabled path, stop-time finalization)
mise run fmt && mise run lint — 0 issues
mise run test:ci — all unit, integration, and E2E canary tests pass

🤖 Generated with Claude Code

Note

Medium Risk
Adds a new v2 checkpoint storage path using custom git refs and wires it into commit/stop-time flows; mistakes could lead to missing or inconsistent checkpoint data even though v1 remains the source of truth. Risk is mitigated by feature-flag gating and best-effort v2 writes that do not block v1.

Overview
Adds feature-flagged v2 dual-write for checkpoints: when checkpoints_v2 is enabled, the manual-commit strategy continues writing v1 checkpoint data while also writing to new custom refs refs/entire/checkpoints/v2/main and refs/entire/checkpoints/v2/full/current.

Introduces V2GitStore with ref management and write/update flows that split data: /main stores checkpoint/session metadata + prompts (no transcript), while /full/current stores the redacted, chunked full.jsonl transcript plus content_hash.txt and replaces prior contents on each write. Validation for write options is centralized via validateWriteOpts, and tests are expanded with new unit tests, integration tests, and test-env helpers to read custom refs.

^{Written by Cursor Bugbot for commit 66841b2. Configure here.}

... for transcript writes to /full/current ref

…v2-refs

… writes

... instead of adding it to the permanent `/main` ref.

setting

finalization

metadata

pfleidi · 2026-03-24T00:01:36Z

cmd/entire/cli/checkpoint/checkpoint.go

-	Transcript  string `json:"transcript"`
-	ContentHash string `json:"content_hash"`
+	Transcript  string `json:"transcript,omitempty"`
+	ContentHash string `json:"content_hash,omitempty"`


These attributes might not be set going forward. Omitting them in such a case made sense to me.

Why would Transcript be missing but Prompt isn't? Should Prompt be omitempty too? (Also, is this for the sub-agent case? Or is there some other case you had in mind?)

The original thought was that by moving the full transcript to the /full/* refs we wouldn't need this anymore unless a checkpoint was pinned. Given that these attributes were only used for the full transcripts we should be okay omitting them unless checkpoints are pinned down the road.

Your comment brought up a few more questions, though:

Do we want this attribute to point to the compactedtranscript.jsonl file instead?

Do we want to introduce new attributes for compacted transcripts and their hashes?

Do we want a way to refer to objects in the /full/* namespace to somehow make the lookup simpler?

Let's take a look at those a bit more closely tomorrow.

Copilot

Pull request overview

Adds a feature-flagged “checkpoints v2” dual-write path so the manual-commit strategy can persist checkpoint data to both the existing v1 metadata branch and the new v2 custom refs, enabling a gradual migration without breaking current read paths.

Changes:

Wire dual-write into CondenseSession and stop-time finalization (UpdateCommitted) behind settings.IsCheckpointsV2Enabled(), with v2 failures treated as best-effort.
Introduce V2GitStore to write v2 checkpoint data to custom refs (/main for metadata/prompts, /full/current for raw transcript + content hash).
Add unit + strategy-level + integration tests, and extend integration TestEnv helpers to read from arbitrary refs.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
cmd/entire/cli/strategy/manual_commit_condensation.go	Builds shared v1/v2 write opts and adds best-effort v2 dual-write during condensation.
cmd/entire/cli/strategy/manual_commit_hooks.go	Adds best-effort v2 dual-write during stop-time checkpoint finalization.
cmd/entire/cli/strategy/manual_commit_test.go	Adds strategy-level tests for v2 dual-write enabled/disabled behavior.
cmd/entire/cli/paths/paths.go	Defines v2 custom ref names under `refs/entire/...`.
cmd/entire/cli/integration_test/v2_dual_write_test.go	Adds integration coverage for full workflow, disabled path, and stop-time finalization.
cmd/entire/cli/integration_test/testenv.go	Adds helpers for reading files from full refs and for checking ref existence.
cmd/entire/cli/checkpoint/v2_store.go	Adds low-level v2 ref creation/state/update primitives.
cmd/entire/cli/checkpoint/v2_committed.go	Implements v2 committed write/update logic for `/main` and `/full/current`.
cmd/entire/cli/checkpoint/v2_store_test.go	Adds unit tests for v2 ref management and committed write/update behavior.
cmd/entire/cli/checkpoint/committed.go	Reuses shared write-option validation via `validateWriteOpts`.
cmd/entire/cli/checkpoint/checkpoint.go	Makes `SessionFilePaths` JSON fields `omitempty` to support v2 layouts with missing fields.

cmd/entire/cli/checkpoint/v2_committed.go

cmd/entire/cli/strategy/manual_commit_hooks.go

cmd/entire/cli/checkpoint/v2_committed.go

…ping

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

cmd/entire/cli/checkpoint/v2_committed.go

cmd/entire/cli/strategy/manual_commit_hooks.go

cmd/entire/cli/checkpoint/v2_committed.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…to feat/checkpoints-v2-refs

pfleidi added 12 commits March 23, 2026 10:52

feat: add v2 checkpoint ref name constants

0eb9599

feat: add V2Store skeleton with ref management helpers

594f54c

feat: add V2GitStore.writeCommittedMain for metadata writes to /main ref

f343da1

feat: add V2GitStore.writeCommittedFullTranscript

96aff83

... for transcript writes to /full/current ref

Merge branch 'main' of github.com:entireio/cli into feat/checkpoints-…

e79e4a2

…v2-refs

feat: add V2GitStore.WriteCommitted composing /main and /full/current…

0c3244c

… writes

Write content hash to ephemeral /full/current ref

4c754d4

... instead of adding it to the permanent `/main` ref.

feat: wire v2 dual-write into CondenseSession, gated by checkpoints_v2

dc3beb0

setting

feat: add V2GitStore.UpdateCommitted and wire into stop-time

6217021

finalization

test: add integration tests for v2 dual-write workflow

2da036a

fix: add omitempty to SessionFilePaths to avoid empty strings in v2

20a37d5

metadata

fix: Remove redundant validation code

66841b2

pfleidi requested a review from a team as a code owner March 23, 2026 23:57

Copilot AI review requested due to automatic review settings March 23, 2026 23:57

Copilot started reviewing on behalf of pfleidi March 23, 2026 23:57 View session

Only mark optional attributes as omitempty

860efa8

pfleidi commented Mar 24, 2026

View reviewed changes

Revert changes to unrelated file

1a5840d

Copilot AI reviewed Mar 24, 2026

View reviewed changes

pfleidi requested review from Soph and computermode March 24, 2026 00:11

fix: address PR review feedback on comments, logging, and context sco…

25b2d9a

…ping

This comment was marked as outdated.

Sign in to view

Remove outdated comment lines

10ab903

pfleidi requested a review from Copilot March 24, 2026 00:50

Copilot started reviewing on behalf of pfleidi March 24, 2026 00:51 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

cmd/entire/cli/checkpoint/v2_committed.go Show resolved Hide resolved

cmd/entire/cli/checkpoint/v2_committed.go Show resolved Hide resolved

cmd/entire/cli/strategy/manual_commit_hooks.go Show resolved Hide resolved

cmd/entire/cli/checkpoint/v2_committed.go Outdated Show resolved Hide resolved

pfleidi and others added 3 commits March 24, 2026 09:19

Evaluate v2 strategy settings only once

65d73a0

Apply suggestion from @Copilot

438e156

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix: accumulate transcripts on /full/current ref instead of replacing

9b1fc99

Merge branch 'feat/checkpoints-v2-refs' of github.com:entireio/cli in…

3ffb586

…to feat/checkpoints-v2-refs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: v2 dual-write for checkpoints behind feature flag#759

feat: v2 dual-write for checkpoints behind feature flag#759
pfleidi wants to merge 20 commits intomainfrom
feat/checkpoints-v2-refs

pfleidi commented Mar 23, 2026 •

edited by cursor bot

Loading

Uh oh!

pfleidi Mar 24, 2026

Uh oh!

computermode Mar 24, 2026

Uh oh!

pfleidi Mar 24, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

Conversation

pfleidi commented Mar 23, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's NOT in scope (future steps per design spec)

Test plan

Uh oh!

pfleidi Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

computermode Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

pfleidi Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

pfleidi commented Mar 23, 2026 •

edited by cursor bot

Loading

pfleidi Mar 24, 2026 •

edited

Loading